Hopefully this won't get too technical, but bear with me 'cos it's late and I've run out of coffee.
The intention with Blackout was to write a screensaver which could be easily extended by the addition of new bits. The other intention was that the new bits should be easy to write so that people with little in-depth knowledge of the WIMP and graphics (such as me) could write their own savers.
To write a screen saver for Blackout you will need the following:
a) A BASIC editor (preferably !Zap, because it's great).
b) Part of a brain. Preferably yours, but you can borrow one if necessary.
c) An idea.
Generally, I find that part c is the hardest. The evidence for this comes from the quality of the savers I supply as standard.
The best way to see how to do it is to look at some of the predefined savers, but a few notes might help.
{subhead}Format
A screen saver for Blackout is a framgent of a BASIC program. The main Blackout program uses BASIC's OVERLAY command to merge the two sections. A screen saver must contain the following two DEFPROCs:
{tab}
{subsub}DEFPROCinitsaver
to initialise the variables used in the screen saver and, if necessary, clear the screen. You could also assemble a machine code routine, but you will need to DIM your own memory for this (or use PROCmemory - see below). 'Stars' uses a machine code routine, and simply sets this up by using a DIM statement in PROCinitsaver to allocate some memory for the code.
If you want the screen background colour to be black, you should include the statement black%=TRUE somewhere in PROCinitsaver. This informs the program that it should use the black window instead of the transparent one.
{subsub}DEFPROCupdatesaver
to provide one 'step' in the animation of the saver. This must be written so that it ENDPROCs after not too long so that the WIMP can carry on polling other applications. For example, in the 'Stars' saver this procedure erases the stars, updates their coordinates, replots them, then returns.
{notab}
You can add as many other procedures as you like, provided they don't have the same names as ones in the main program (see below). The same applies to your own variables.
You don't have to worry about checking for key presses or mouse movements or anything because the main program does that for you.
The saver must also contain some REM statements at the start of the file:
{tab}
REM <Saver Name>
REM RiscOSVer,350
REM Parameters:<description1>,<default1>
REM Parameters:<description2>,<default2>
REM Parameters:EndOpts
REM Author:<author's name>
REM Description:<short description>
{notab}
The order of these REM statements is crucial. Also note that everything is CASE SeNsItIvE. The first line is obvious. It doesn't do anything, but it must be there for the lazily-coded program to work.
The RiscOSVer line is optional. After this parameter you can specify a number which is the earliest version of Risc OS that this screen saver can run on. So to allow your saver to be run only on Risc OS 3.50 and above, you put RiscOSVer,350. If you leave this line out, the saver can be used on all versions of Risc OS.
The Parameters: lines are the parameters. You can have up to 11 (or is it 10 - I can never remember) parameters. The <description> should be short enough to fit in the window. The <default> should be a sensible default. The REM Parameters:EndOpts must ALWAYS be there and is CASE SENSITIVE. If you have no parameters, just include this line.
The last two lines are what will be displayed in the "Saver Information" box.
To include a Faster variable (see above) you MUST have a parameter 'Faster', which when given the value 1 causes the variable bogie_eater% to be set to TRUE in PROCinitsaver. Blackout takes care of the rest.
Your screen saver must be mode-independent. To help you in this, some variables are supplied by the main program.
{subhead}Checking Parameters
You may wish to check that the parameters are valid. To do this, put at the start of PROCinitsaver
IF <parameter not valid> PROClemon("some descriptive text")
That's all there is to it.
{subhead}Supplied Variables
The main blackout program sets up a number of variables which the saver can use. These are:
{tab}
{subsub}options$(0)-options$(10)
contain each of the parameters as passed to blackout by the configuration program. In the above example options$(0) would be "30" and options$(1) would be "40". Note that all these are string variables.
{subsub}numcols%
is the number of colours that the current screen mode supports.
{subsub}scrx%,scry%
are the screen mode x and y size in OS units.
{subsub}xeigen%,yeigen%
are the x and y eigen factors - i.e. the log (base 2) of the number of OS units per pixel.
{subsub}handle%
If you want to use an outline font you will need a variable to store the font handle from Font_FindFont. I recommend you use handle% for this because then Blackout will do a Font_LoseFont when it closes down. If you use your own variable the font will remain open (unless you edit Blackout, which I would rather you didn't).
{notab}
{subhead}Useful Procedures
Some procedures are also supplied by the program which may be of general use:
{tab}
{subsub}PROCblack
clears the screen to black. It's not very fast but it works. If you want to use a screen saver with a black background, you MUST call this procedure once. If you don't, odd things may happen. On Risc OS 3.50 and above, this starts off the screen fade-to-black.
{subsub}FNreadvar
will read a system variable and return the result as a string.
{subsub}PROCmemory
is used to gain a large block of memory if, for instance, you want to set up a large user sprite area. The procedure takes one parameter, which is the amount of memory (in bytes) that you want. The variable rmablock% points to the start of this memory. The program uses SYS"Wimp_SlotSize" to get the memory, but the variable is called rmablock% because I originally used the RMA. So there. This procedure will abort the program if the required memory cannot be grabbed.
{subsub}PROCcycle
On RiscOS 3.50 and above this performs palette cycling using the CompoSupport Gamma Correction module written by Rob Davison. Call it from PROCupdatesaver once per iteration and it will cycle your palette for you. The Psych savers use this.
{notab}
{subhead}Changing Screen Mode
{subsub}(RiscOS 3.50 and above ONLY)
Some of the screen savers change mode before they start. To do this, use the following procedure:
In PROCinitsaver call PROCrecovermode, which gets Blackout ready to restore the current mode once the screen saver has finished, then set up anything else you want, then call PROCblack.
In PROCupdatesaver start with the following:
DEFPROCupdatesaver
IF NOT modechanged% THEN
PROCsixteenmillion
<anything else you want to do now that the mode has changed>
ENDIF
<etc. etc.>
PROCsixteenmillion will change to 800x600 and 16 million colours by default, but if you want the user to be able to specify a mode string then just include a parameter for it and use it to set the variable changemode$.
Note that calling PROCsixteenmillion does not guarantee that you will get that mode - someone may have less than 2MB of VRAM.
{subhead}Reserved Names
Procedures in your fragment of program must not have the same names as ones in the main program. The following PROC and FN names are reserved:
